Bundle content handover feature has been introduced in RHQ 4.12. Its purpose is to delegate the deployment of some (or all) of the content included in the bundle archive to the bundle target resource component. Thus the handover name: content handed over to a resource component.
Handover is a mean to make the bundle target resource component participate in the bundle deployment. Sometimes your managed resources don't rely on filesystem changes to deploy your applications. Think of EAP 6 domain mode as an example. The agent plugin however knows how to communicate with your resources, how to upload some content and how to deploy it.
The handover feature will let you send some of the bundle content to the target resource component. You will have to define an action and some action parameters too, because the plugin component could do many different things with the content:
deploy it as an application
run it as a CLI script
... etc
While content handover implementation at the plugin container level is independent of the bundle type, only the agent plugin for ANT Bundles is prepared to use it. In other words, handover is not supported by the agent plugin of the File template bundle type.
If you're a bundle type developer, know that the org.rhq.core.pluginapi.bundle.BundleManagerProvider#handoverContent method was added in RHQ 4.12. It's the hook which will let you hand content over to the bundle target resource.
Not all bundle target resource types support bundle content handover. The plugin component class needs to implement the org.rhq.core.pluginapi.bundle.BundleHandoverFacet interface. The agent plugin container will fail the bundle deployment if it doesn't.
Plugin developers should document in the plugin descriptor the list of actions and associated parameters their bundle target resource types support.
The bundle subsystem in RHQ is filesystem-oriented. This means that when you're reverting you're actually restoring backed-up files and re-invoking the previous bundle version recipe. There's no "uninstall" mechanism. As for the purge, it will only clean the bundle destination directory according to the deployment unit compliance attribute value.
Consequently, handed over content cannot be reverted or purged. You can only "move forward", you cannot undeploy content to go backwards.
Keep in mind when setting up bundle permissions that the content handed over to the target resource component could compromise your system. For example, the AS7 / EAP6 plugin lets the bundle developer execute an AS7 / EAP6 CLI script with extended permissions (the plugin configuration credentials are generally those of a super user).
It is recommended that the bundle content and recipes get reviewed before they are uploaded to the RHQ server.
|
Attribute Name |
Description |
|
action |
Mandatory. The name of the action the target resource component should execute. |
|
failonerror |
Optional. Whether the ANT recipe build should fail if the target resource component reports a failure. true or false. Defaults to true. |
The following tags may have a (unique) <rhq:handover> child tag:
If two pieces of content in the bundle need to be handed over to the target resource component, they will be sent in the same order as declared in the bundle recipe. Let's take an example.
<rhq:file name="prepareDatasource.cli" replace="true">
<rhq:handover action="execute-script" failonerror="false"/>
</rhq:file>
<rhq:archive name="website.war">
<rhq:handover action="deployment">
<rhq:handover-param name="runtimeName" value="${myapp.runtime.name}"/>
<rhq:handover-param name="serverGroup" value="${server.group}"/>
</rhq:handover>
</rhq:archive>
Here the prepareDatasource.cli file content will always be handed over to the target resource component before the website.war archive content.
|
Attribute Name |
Description |
|
name |
Mandatory. The name of the parameter |
|
value |
Mandatory. The value of the parameter |
<rhq:handover> tag may have zero, one or more <rhq:handover-param> child tags.
<?xml version="1.0"?>
<project name="handover-bundle" default="main" xmlns:rhq="antlib:org.rhq.bundle">
<rhq:bundle name="example.com (EAP 6)" version="1.1"
description="example.com corporate website hosted on EAP 6">
<rhq:input-property
name="myapp.runtime.name"
defaultValue="website.war"
required="true"/>
<rhq:input-property
name="server.group"
defaultValue="main-server-group-01"
required="true"/>
<rhq:deployment-unit name="example.com deployment unit" compliance="filesAndDirectories">
<rhq:file name="prepareDatasource.cli" replace="true">
<rhq:handover action="execute-script" failonerror="false"/>
</rhq:file>
<rhq:archive name="website.war">
<rhq:handover action="deployment">
<rhq:handover-param name="runtimeName" value="${myapp.runtime.name}"/>
<rhq:handover-param name="serverGroup" value="${server.group}"/>
</rhq:handover>
</rhq:archive>
</rhq:deployment-unit>
</rhq:bundle>
<target name="main"/>
</project>